home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
AmigActive 10
/
AACD 10.iso
/
AACD
/
Programming
/
MuManual
/
Autodocs
/
memory.doc
< prev
next >
Wrap
Text File
|
1999-11-20
|
15KB
|
489 lines
TABLE OF CONTENTS
memory.library/--Background--
memory.library/CreateAdrSpace
memory.library/DeleteAdrSpace
memory.library/AllocVMPool
memory.library/DeleteVMPool
memory.library/AttachTask
memory.library/DetachTask
memory.library/AllocVMVec
memory.library/FreeVMVec
memory.library/LockVMVec
memory.library/UnlockVMVec
memory.library/--Background-- memory.library/--Background--
PURPOSE
The memory.library provides functions for memory allocation and
deallocation that are superior to those of the exec.library.
The functions of this library will provide so called "virtual memory"
by using the mmu.library, memory that can be swapped to disk
transparently to the application. Hence, applications will be usually
able to allocate more memory than physically available.
Certain access restrictions arise for memory allocated by the
memory.library. First, you can't access it in Forbid() or Disable()
state. Second, it can't be shared amongst different pools. You
must explicitly attach the tasks that should be able to access memory
from a given pool. Thus, you can't use this kind of memory for keeping
Os structures since they may be passed to different tasks for further
processing. Third, you MAY NOT access virtual memory in a situation
where file I/O would be impossible. That is, DO NOT access this mem
while:
- holding a lock on the dos.library handler lists
- disabling the filing system of the swap partition
- making the swapping exec.device unaccessible
- taking over the hardware
The mmu.library will try to detect such situations and will throw
a guru if that's possible. However, if it is not, these situations
will result in a dead-lock! Keep care!
This restriction can be somewhat weakened by the LockVMVec/UnlockVMVec
functions. By calling these functions, you can lock a given memory
vector in memory and hence, will be able access it WITHIN Forbid().
It returns a pointer to the physical location of that memory block
which must be used if that memory is passed to a different task or
other hardware components.
This kind of "virtual memory" is of course some kind of a
"poor man's solution" for implementing virtual memory. No exec
function will be patched and old programs will continue to work
without any change. The library is of course of limited or no use
at all for old programs since it doesn't redirect standard memory
allocation functions to their "virtual" counterparts. Thus, this
is a very "conservative" approach to overcome this limitation of
AmigaOs.
A special "VMM/GigaMem" patch might be made available that uses
the functions of this library to provide virtual memory to every
task. However, since this CAN'T be fully compatible to old programs
and may, therefore, cause some compatibility problems. It should be
up to the user if she/he likes to install a patch like this or not,
but it should NOT the way how virtual memory enters AmigaOs, at
least not now.
The basic objects the memory.library handles is first the
"AddressSpace" object. It defines - as it says - an common
address space for the tasks attachted to it. It is the memory.library
implementation of the mmu.library "context". Each address space can
be linked to as many tasks as you wish, but a task can be attached
to only one address space at a time.
The actual memory allocation is done from "VMPools". They are the
memory.library counterpart of the exec "memory pools". Each address
space may contain as many "VMPools" as you wish, but only tasks
attachted to the address space of the pool can use it.
memory.library/CreateAdrSpace memory.library/CreateAdrSpace
NAME
CreateAdrSpace - create a new address space.
SYNOPSIS
BOOL CreateAdrSpace( );
d0
BOOL CreateAdrSpace( VOID );
FUNCTION
Build a new address space and attach the calling task to this
address space.
INPUTS
none.
RETURNS
a true/false boolean success indicator.
NOTES
This call will build a new mmu.library "Context" for the calling
task and will enter this context for this task. The task calling
this function should not be attachted to any other address space
or this task will fail. A task can be attached to one address
space at a time only.
This call will change the tc_Switch() and tc_Launch() function
pointers of the calling task.
SEE ALSO
DeleteAdrSpace(), exec/tasks.h
memory.library/DeleteAdrSpace memory.library/DeleteAdrSpace
NAME
DeleteAdrSpace - delete an address space.
SYNOPSIS
DeleteAdrSpace( );
DeleteAdrSpace( void );
FUNCTION
This call deletes the address space of the calling task. It will
leave the private context build for this address space and will
enter the global context.
INPUTS
none.
RETURNS
nothing.
NOTES
This call uses the CurrentContext() call of the mmu.library and
deletes this context. The task is then re-attachted to the global
common context. No virtual memory must be used at that time, nor
any other task may be attachted to this address space.
It is safe to call this function if the calling task isn't attached
to any address space. Nothing will happen in this case.
SEE ALSO
CreateAdrSpace(), mmu.library/CurrentContext()
memory.library/AllocVMPool memory.library/AllocVMPool
NAME
AllocVMPool - create a pool of virtual memory.
SYNOPSIS
pool = AllocVMPool( reqments, attributes );
d0 d0 d1
VMPool * AllocVMPool( ULONG, ULONG );
FUNCTION
Creates a memory pool for virtual memory and adds the calling task
to the list of tasks that can safely use this pool.
INPUTS
reqments - an exec style memory attributes flags field.
This defines the memory type the pool will be taken from,
not ANY implications about the logical addresses asssigned
to the memory allocated from that pool. Thus, if you call
LockVMVec() later on, that vector will be mapped to the
memory described by the reqments above.
The following bits, defined in exec/memory.h will be
ignored:
MEMF_PUBLIC - as the pool is always private in
this sense.
MEMF_CLEAR - as this flag must be specified
individually when allocating memory from the pool.
attributes - special attribute flags.
VMEMF_PRIVATE - make the memory in the pool invalid
to other tasks.
VMEMF_PROTECT - protect the underlying MMU context.
VMEMF_NONCACHE - mark the memory in the pool
explicitly as noncacheable
(defaults to the cache type of the physical memory)
VMEMF_PRECISE - mark the memory in the pool as
requiring the precise exception model.
(only for special MMUs, not available in general)
Implies VMEMF_NONCACHE
VMEMF_SERIALIZED- mark the memory as serialized non-
cacheable.
(only for special MMUs, not available in general).
RETURNS
A handle to the pool or NULL in case of failure. The calling
task will be prepared to use the memory in the pool.
NOTES
To use this call, a private address context must have been
build before.
SEE ALSO
CreateAdrSpace(), DeleteVMPool(), exec/memory.h
memory.library/DeleteVMPool memory.library/DeleteVMPool
NAME
DeleteVMPool - Delete a virtual memory pool.
SYNOPSIS
result = DeleteVMPool( pool);
d0 a0
BOOL DeleteVMPool (VMPool *);
FUNCTION
Deletes the given virtual memory pool in question, releases the
memory occupied by the pool and the release the used space on disk.
INPUTS
pool - a handle to a VMPool as created by AllocVMPool.
Passing in NULL is safe.
RESULTS
A boolean that indicates whether some memory in the pool is
still allocated. Can be usually ignored but is useful for
debugging.
NOTES
SEE ALSO
AllocVMPool()
memory.library/AttachTask memory.library/AttachTask
NAME
AttachTask - attach a task to the address space of the calling task.
SYNOPSIS
result = AttachTask( task);
d0 a1
BOOL AttachTask(struct Task *);
FUNCTION
To allow another task sharing the same address space than the calling
task, this new task must be attached to the common address space
with this call. Afterwards, the task passed in the parameter may
use the same virtual memory pools as the calling task.
INPUTS
task - The task to be added to the allowed tasks for the
address space of the calling task.
RETURNS
a boolean indicating whether it was possible to add the task to
the adrspc.
NOTES
It is intentionally not possible to add tasks to an address space
of a different task than the calling one.
SEE ALSO
DetachTask()
memory.library/DetachTask memory.library/DetachTask
NAME
DetachTask - remove the calling task from its address space.
SYNOPSIS
DetachTask( );
VOID DetachTask( VOID );
FUNCTION
Remove the calling task from its address space and let it enter
the common context again. The address space itself will continue
to exist.
INPUTS
none.
RETURNS
nothing.
NOTES
The current task is, after calling this function, no longer allowed
to use any virtual memory allocated by the memory.library pool
functions of that pool.
The only use of this function is to pass an address space from a
creator task to its children, i.e. by first calling CreateAdrSpace,
then launching the child process, attaching the child process to
that address space and removing the creator task from that pool.
It's then up to the children to remove themselves from that address
space on exit and to delete the address space created this way.
It is safe to call this function if the current task isn't attached
to any address space. Nothing will happen in this case.
SEE ALSO
AttachTask(), CreateAdrSpace()
memory.library/AllocVMVec memory.library/AllocVMVec
NAME
AllocVMVec - allocate virtual memory from a pool.
SYNOPSIS
mem = AllocVMVec( pool, bytesize, flags);
d0 a0 d0 d1
void * AllocVMVec( Pool *, ULONG, ULONG);
FUNCTION
This function allocates memory from a given virtual pool.
INPUTS
pool - The pool to allocate the memory from.
bytesize- The size of the memory required. This might be larger
than the amount of physical memory available, but you won't
be able to access the complete memory block at once or
to lock it in memory.
flags - allocation flags. The following flags are used:
MEMF_PUBLIC The returned memory will be public, i.e.
non-virtual.
MEMF_REVERSE The memory will be allocated from the pool
in reverse order.
MEMF_CLEAR The memory will be wiped out before it is
passed back.
All other memory relevant flags as the caching mode and whether
the memory is in CHIP or in FAST memory is determined by the
flags used when allocating the pool.
RETURNS
the memory block allocated or NULL for failure. If the calling
task is a process, the pr_Result2 field will be set to
ERROR_NO_FREE_STORE (103).
NOTES
This call may break a Forbid() state. It may swap out pages of
virtual memory if necessary.
The returned memory will be aligned to at least one longword,
the size might be rounded somewhat, but will at least contain
the number of bytes specified by the argument.
To be able to allocate memory from the pool, the calling task
must have been the creator of that pool or must have been added
to the list of allowed tasks for that pool with AttachTask().
SEE ALSO
FreeVMVec(), AttachTask(), exec/memory.h
memory.library/FreeVMVec memory.library/FreeVMVec
NAME
FreeVMVec - allocate virtual memory from a pool.
SYNOPSIS
FreeVMVec( pool, mem);
a0 a1
VOID FreeVMVec( Pool *, void *);
a0 a1
FUNCTION
This function returns memory allocated from the pool.
INPUTS
pool - The pool the memory was taken from.
mem - The memory vector to free. No byte size is passed,
the size is implicit. It is safe to pass NULL here. No
action is performed in this case.
RETURNS
none.
NOTES
This call may break a Forbid() state. It may swap in pages of
virtual memory if necessary.
To be able to call this function, the calling task must either
the creator of the pool, or any other task that has been attached
to the pool with AttachTask().
SEE ALSO
AllocVMVec(), AttachTask()
memory.library/LockVMVec memory.library/LockVMVec
NAME
LockVMVec - Lock a memory vector in memory.
SYNOPSIS
phmem = LockVMVec( pool, mem);
d0 a0 a1
void * LockVMVec( Pool *, void *);
FUNCTION
This function locks the specified vector in memory such that it
is guaranteed to be non-virtual and accessable by all tasks and
to all Os functions. The physical address of that memory is
returned as it should be used to "the outher world".
INPUTS
pool - a handle to the memory pool the memory was taken from.
mem - the pointer to the memory vector in question. This is
the logical address returned by AllocVMVec, not a physical
address.
RETURNS
a pointer to the location of that memory block in physical memory
or NULL if not enough physical memory is available to swap in that
page in question.
NOTES
The calling task must be either the task that created the pool,
or any other task that was attachted to that pool.
Using this call turns effectively private virtual memory in
standard exec memory. Therefore, not too many virtual pages should
be locked and this call should be avoided in general unless you
need to swap in the virtual memory in question TEMPORARILY. Call
UnlockVMVec() as soon as possible to allow swapping out of the
memory again.
Due to the memory paging of the MMU, this call swaps actually more
than the desired memory block in.
This call may break a forbid state, it MAY fail if not enough
physical memory is available.
This call nests - each call to LockVMVec() must be matched by one
call to UnlockVMVec().
SEE ALSO
UnlockVMVec()
memory.library/UnlockVMVec memory.library/UnlockVMVec
NAME
UnlockVMVec - Lock a memory vector in memory.
SYNOPSIS
UnlockVMVec( pool, mem);
a0 a1
VOID UnlockVMVec( Pool *, void *);
FUNCTION
This function unlocks a memory block and re-allows swapping out
of that memory block.
INPUTS
pool - a handle to the memory pool the memory was taken from.
mem - the pointer to the memory vector in question, the
logical address.
RETURNS
nothing.
NOTES
The calling task must be either the task that created the pool,
or any other task that was attachted to that pool.
This call turns locked memory again in virtual memory and allows
the library to swap it out again.
DO NOT use the physical address returned by LockVMMem() again
after having called this function.
SEE ALSO
LockVMVec()